  <!DOCTYPE html>
  <html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="generator" content="pandoc" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
    <title>GTK 4 tutorial</title>
    <style>
      code{white-space: pre-wrap;}
      span.smallcaps{font-variant: small-caps;}
      span.underline{text-decoration: underline;}
      div.column{display: inline-block; vertical-align: top; width: 50%;}
      div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
      ul.task-list{list-style: none;}
      pre{overflow: visible;}
      pre > code.sourceCode { white-space: pre; position: relative; }
      pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
      pre > code.sourceCode > span:empty { height: 1.2em; }
      code.sourceCode > span { color: inherit; text-decoration: inherit; }
      div.sourceCode { margin: 1em 0; }
      pre.sourceCode { margin: 0; }
      @media screen {
      div.sourceCode { overflow: auto; }
      }
      @media print {
      pre > code.sourceCode { white-space: pre-wrap; }
      pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
      }
      pre.numberSource code
        { counter-reset: source-line 0; }
      pre.numberSource code > span
        { position: relative; left: -4em; counter-increment: source-line; }
      pre.numberSource code > span > a:first-child::after
        { content: counter(source-line);
          position: relative; left: -1em; text-align: right; vertical-align: baseline;
          border: none; display: inline-block;
          -webkit-touch-callout: none; -webkit-user-select: none;
          -khtml-user-select: none; -moz-user-select: none;
          -ms-user-select: none; user-select: none;
          padding: 0 4px; width: 4em;
          color: #aaaaaa;
        }
      pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa;  padding-left: 4px; }
      div.sourceCode
        {   }
      @media screen {
      pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
      }
      code span.al { color: #ff0000; font-weight: bold; } /* Alert */
      code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
      code span.at { color: #7d9029; } /* Attribute */
      code span.bn { color: #40a070; } /* BaseN */
      code span.bu { } /* BuiltIn */
      code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
      code span.ch { color: #4070a0; } /* Char */
      code span.cn { color: #880000; } /* Constant */
      code span.co { color: #60a0b0; font-style: italic; } /* Comment */
      code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
      code span.do { color: #ba2121; font-style: italic; } /* Documentation */
      code span.dt { color: #902000; } /* DataType */
      code span.dv { color: #40a070; } /* DecVal */
      code span.er { color: #ff0000; font-weight: bold; } /* Error */
      code span.ex { } /* Extension */
      code span.fl { color: #40a070; } /* Float */
      code span.fu { color: #06287e; } /* Function */
      code span.im { } /* Import */
      code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
      code span.kw { color: #007020; font-weight: bold; } /* Keyword */
      code span.op { color: #666666; } /* Operator */
      code span.ot { color: #007020; } /* Other */
      code span.pp { color: #bc7a00; } /* Preprocessor */
      code span.sc { color: #4070a0; } /* SpecialChar */
      code span.ss { color: #bb6688; } /* SpecialString */
      code span.st { color: #4070a0; } /* String */
      code span.va { color: #19177c; } /* Variable */
      code span.vs { color: #4070a0; } /* VerbatimString */
      code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
      div.sourceCode { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
      pre:not(.sourceCode) { margin: 10px; padding: 16px 10px 8px 10px; border: 2px solid silver; background-color: ghostwhite; overflow-x:scroll}
      table {margin-left: auto; margin-right: auto; border-collapse: collapse; border: 1px solid;}
      th {padding: 2px 6px; border: 1px solid; background-color: ghostwhite;}
      td {padding: 2px 6px; border: 1px solid;}
      img {display: block; margin-left: auto; margin-right: auto;}
      figcaption {text-align: center;}
    </style>
  </head>
  <body style="padding-top: 70px;">
    <div class="container">
    <nav class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
      <div class="container-fluid">
        <span class="navbar-brand">Gtk4 tutorial</span>
        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
          <span class="navbar-toggler-icon"></span>
        </button>
        <div class="collapse navbar-collapse" id="navbarSupportedContent">
          <ul class="navbar-nav me-auto mb-2 mb-lg-0">
            <li class="nav-item">
<a class="nav-link" href="index.html">Home</a>
</li>

            <li class="nav-item">
<a class="nav-link" href="sec3.html">Prev: section3</a>
</li>

            <li class="nav-item">
<a class="nav-link" href="sec5.html">Next: section5</a>
</li>

          </ul>
        </div>
      </div>
    </nav>
<h1 id="widgets-1">Widgets (1)</h1>
<h2 id="gtklabel-gtkbutton-and-gtkbox">GtkLabel, GtkButton and
GtkBox</h2>
<h3 id="gtklabel">GtkLabel</h3>
<p>In the previous section we made a window and displayed it on the
screen. Now we go on to the next topic, where we add widgets to this
window. The simplest widget is GtkLabel. It is a widget with text in
it.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
misc/lb1.c @@@</p>
<p>Save this program to a file <code>lb1.c</code>. Then compile and run
it.</p>
<pre><code>$ comp lb1
$ ./a.out</code></pre>
<p>A window with a message “Hello.” appears.</p>
<figure>
<img src="image/screenshot_lb1.png" alt="Screenshot of the label" />
<figcaption aria-hidden="true">Screenshot of the label</figcaption>
</figure>
<p>There’s only a little change between <code>pr4.c</code> and
<code>lb1.c</code>. A program <code>diff</code> is good to know the
difference between two files.</p>
<p>@@<span class="citation" data-cites="shell">@shell</span> cd misc;
diff pr4.c lb1.c @@@</p>
<p>This tells us:</p>
<ul>
<li>A signal handler <code>app_activate</code> doesn’t have
<code>user_data</code> parameter. If the fourth argument of
<code>g_signal_connect</code> is NULL, you can leave out
<code>user_data</code>.</li>
<li>The definition of a new variable <code>lab</code> is added.</li>
<li>The title of the window is changed.</li>
<li>A label is created and connected to the window as a child.</li>
</ul>
<p>The function
<code>gtk_window_set_child (GTK_WINDOW (win), lab)</code> makes the
label <code>lab</code> a child widget of the window <code>win</code>. Be
careful. A child widget is different from a child object. Objects have
parent-child relationships and widgets also have parent-child
relationships. But these two relationships are totally different. Don’t
be confused. In the program <code>lb1.c</code>, <code>lab</code> is a
child widget of <code>win</code>. Child widgets are always located in
their parent widget on the screen. See how the window has appeared on
the screen. The application window includes the label.</p>
<p>The window <code>win</code> doesn’t have any parents. We call such a
window top-level window. An application can have more than one top-level
window.</p>
<h3 id="gtkbutton">GtkButton</h3>
<p>The next widget is GtkButton. It displays a button on the screen with
a label or icon on it. In this subsection, we will make a button with a
label. When the button is clicked, it emits a “clicked” signal. The
following program shows how to catch the signal and do something.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
misc/lb2.c @@@</p>
<p>Look at the line 17 to 19. First, it creates a GtkButton instance
<code>btn</code> with a label “Click me”. Then, adds the button to the
window <code>win</code> as a child. Finally, connects a “clicked” signal
of the button to the handler <code>click_cb</code>. So, if
<code>btn</code> is clicked, the function <code>click_cb</code> is
invoked. The suffix “cb” means “call back”.</p>
<p>Name the program <code>lb2.c</code> and save it. Now compile and run
it.</p>
<figure>
<img src="image/screenshot_lb2.png" alt="Screenshot of the label" />
<figcaption aria-hidden="true">Screenshot of the label</figcaption>
</figure>
<p>A window with the button appears. Click the button (it is a large
button, you can click everywhere in the window), then a string
“Clicked.” appears on the terminal. It shows the handler was invoked by
clicking the button.</p>
<p>It’s good that we make sure that the clicked signal was caught and
the handler was invoked by using <code>g_print</code>. However, using
<code>g_print</code> is out of harmony with GTK, which is a GUI library.
So, we will change the handler. The following code is
<code>lb3.c</code>.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
misc/lb3.c click_cb app_activate @@@</p>
<p>And the difference between <code>lb2.c</code> and <code>lb3.c</code>
is as follows.</p>
<p>@@<span class="citation" data-cites="shell">@shell</span> cd misc;
diff lb2.c lb3.c @@@</p>
<p>The changes are:</p>
<ul>
<li>The function <code>g_print</code> in <code>lb2.c</code> was deleted
and two lines are inserted.
<ul>
<li><code>click_cb</code> has the second parameter, which comes from the
fourth argument of the <code>g_signal_connect</code> at the line 19. One
thing to be careful is the types are different between the second
parameter of <code>click_cb</code> and the fourth argument of
<code>g_signal_connect</code>. The former is <code>GtkWindow *</code>
and the latter is <code>GtkWidget *</code>. The compiler doesn’t
complain because <code>g_signal_connect</code> uses gpointer (general
type of pointer). In this program the instance pointed by
<code>win</code> is a GtkApplicationWindow object. It is a descendant of
GtkWindow and GtkWidget class, so both <code>GtkWindow *</code> and
<code>GtkWidget *</code> are correct types for the instance.</li>
<li><code>gtk_destroy (win)</code> destroys the top-level window. Then
the application quits.</li>
</ul></li>
<li>The label of <code>btn</code> is changed from “Click me” to
“Close”.</li>
<li>The fourth argument of <code>g_signal_connect</code> is changed from
<code>NULL</code> to <code>win</code>.</li>
</ul>
<p>The most important change is the fourth argument of the
<code>g_signal_connect</code>. This argument is described as “data to
pass to handler” in the definition of <a
href="https://docs.gtk.org/gobject/func.signal_connect.html"><code>g_signal_connect</code></a>.</p>
<h3 id="gtkbox">GtkBox</h3>
<p>GtkWindow and GtkApplicationWindow can have only one child. If you
want to add two or more widgets in a window, you need a container
widget. GtkBox is one of the containers. It arranges two or more child
widgets into a single row or column. The following procedure shows the
way to add two buttons in a window.</p>
<ul>
<li>Create a GtkApplicationWindow instance.</li>
<li>Create a GtkBox instance and add it to the GtkApplicationWindow as a
child.</li>
<li>Create a GtkButton instance and append it to the GtkBox.</li>
<li>Create another GtkButton instance and append it to the GtkBox.</li>
</ul>
<p>After this, the Widgets are connected as the following diagram.</p>
<figure>
<img src="image/box.png" alt="Parent-child relationship" />
<figcaption aria-hidden="true">Parent-child relationship</figcaption>
</figure>
<p>The program <code>lb4.c</code> is as follows.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
misc/lb4.c @@@</p>
<p>Look at the function <code>app_activate</code>.</p>
<p>After the creation of a GtkApplicationWindow instance, a GtkBox
instance is created.</p>
<div class="sourceCode" id="cb2"><pre class="sourceCode c"><code class="sourceCode c"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a>box <span class="op">=</span> gtk_box_new<span class="op">(</span>GTK_ORIENTATION_VERTICAL<span class="op">,</span> <span class="dv">5</span><span class="op">);</span></span>
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a>gtk_box_set_homogeneous <span class="op">(</span>GTK_BOX <span class="op">(</span>box<span class="op">),</span> TRUE<span class="op">);</span></span></code></pre></div>
<p>The first argument arranges the children of the box vertically. The
orientation constants are defined like this:</p>
<ul>
<li>GTK_ORIENTATION_VERTICAL: the children widgets are arranged
vertically</li>
<li>GTK_ORIENTATION_HORIZONTAL: the children widgets are arranged
horizontally</li>
</ul>
<p>The second argument is the size between the children. The unit of the
length is pixel.</p>
<p>The next function fills the box with the children, giving them the
same space.</p>
<p>After that, two buttons <code>btn1</code> and <code>btn2</code> are
created and the signal handlers are set. Then, these two buttons are
appended to the box.</p>
<p>@@<span class="citation" data-cites="include">@include</span>
misc/lb4.c click1.cb @@@</p>
<p>The function <code>gtk_button_get_label</code> returns a text from
the label. The string is owned by the button and you can’t modify or
free it. The <code>const</code> qualifier is necessary for the string
<code>s</code>. If you change the string, your compiler will give you a
waring.</p>
<p>You always need to be careful with the const qualifier when you see
the GTK 4 API reference.</p>
<figure>
<img src="image/screenshot_lb4.png" alt="Screenshot of the box" />
<figcaption aria-hidden="true">Screenshot of the box</figcaption>
</figure>
<p>The handler corresponding to <code>btn1</code> toggles its label. The
handler corresponding to <code>btn2</code> destroys the top-level window
and the application quits.</p>
    </div>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
  </body>
  </html>
